<!--
  ****************************************************************************
  * Copyright 2018-2024,2025 Thomas E. Dickey                                *
  * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_pad.3x,v 1.79 2025/01/19 00:51:10 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_pad 3x 2025-01-18 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_pad 3x 2025-01-18 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>                     Library calls                    <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>newpad</STRONG>, <STRONG>subpad</STRONG>, <STRONG>prefresh</STRONG>, <STRONG>pnoutrefresh</STRONG>, <STRONG>pechochar</STRONG>, <STRONG>pecho_wchar</STRONG> - create
       and display <EM>curses</EM> pads


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>WINDOW</STRONG> <STRONG>*newpad(int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>);</STRONG>
       <STRONG>WINDOW</STRONG> <STRONG>*subpad(WINDOW</STRONG> <STRONG>*</STRONG><EM>parent</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>prefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>pnoutrefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>pechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>pecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       A <EM>curses</EM> <EM>pad</EM> is like a window, except that it is not restricted by  the
       screen  size,  and is not necessarily associated with a particular part
       of the screen.  Pads can be used when a large window  is  needed,  only
       part  of  which  is  to  be  visible  on  the  screen.   Pads  are  not
       automatically refreshed by scrolling or input-echoing operations.

       Pads  cannot  be  refreshed  with   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>;   use   <STRONG>prefresh</STRONG>   or
       <STRONG>pnoutrefresh</STRONG> instead.


</PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
       <STRONG>newpad</STRONG>  creates  and returns a pointer to a new pad data structure with
       the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.


</PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
       <STRONG>subpad</STRONG> creates and returns a pointer to a subwindow within a  pad  with
       the  given  number  of  lines,  <EM>nlines</EM>,  and  columns,  <EM>ncols</EM>.   Unlike
       <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>, which uses screen coordinates, the new  pad  is  placed  at
       position (<EM>begin</EM><STRONG>_</STRONG><EM>y</EM>, <EM>begin</EM><STRONG>_</STRONG><EM>x</EM>) relative to its parent.  Thus, changes made
       to one pad can affect both.  When operating on a subpad,  it  is  often
       necessary  to  call  <STRONG><A HREF="curs_touch.3x.html">touchwin(3x)</A></STRONG>  or  <STRONG><A HREF="curs_touch.3x.html">touchline(3x)</A></STRONG>  on  <EM>parent</EM> before
       calling <STRONG>prefresh</STRONG>.


</PRE><H3><a name="h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
       <STRONG>prefresh</STRONG>  and  <STRONG>pnoutrefresh</STRONG>   are   analogous   to   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>   and
       <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>  except that they operate on pads rather than windows.
       They require additional parameters are needed to indicate what portions
       of the pad and screen are involved.

       <STRONG>o</STRONG>   <EM>pminrow</EM>  and  <EM>pmincol</EM>  specify  the  upper  left-hand  corner  of a
           rectangular view of the pad.

       <STRONG>o</STRONG>   <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> specify the vertices of  the
           rectangle to be displayed on the screen.

       The lower right-hand corner of the rectangle to be displayed in the pad
       is calculated from the screen coordinates, since the rectangles must be
       the same size.  Both rectangles must be entirely contained within their
       respective structures.  <EM>curses</EM> treats negative values of any  of  these
       parameters as zero.


</PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
       <STRONG>pechochar</STRONG>  is functionally equivalent to calling <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> followed by
       <STRONG>prefresh</STRONG>.  It suggests to the  <EM>curses</EM>  optimizer  that  only  a  single
       character  is  being  output; a considerable performance benefit may be
       thus enjoyed.  The location of the character <EM>ch</EM> written to the  pad  is
       used to populate the arguments to <STRONG>prefresh</STRONG>.


</PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
       <STRONG>pecho_wchar</STRONG> is functionally equivalent to calling <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> followed
       by <STRONG>prefresh</STRONG>.  It suggests to the <EM>curses</EM> optimizer that  only  a  single
       wide  character is being output; a considerable performance benefit may
       be thus enjoyed.  The location of the character <EM>wch</EM> written to the  pad
       is used to populate the arguments to <STRONG>prefresh</STRONG>.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       Functions  that  return  an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon
       successful completion.

       Functions that return pointers return <EM>NULL</EM> on error, and set  <EM>errno</EM>  to
       <STRONG>ENOMEM</STRONG>.

       In this implementation

          <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
               return  <STRONG>ERR</STRONG>  if the window pointer is null, or if the window is
               not really a pad or if the area to refresh  extends  off-screen
               or if the minimum coordinates are greater than the maximum.

          <STRONG>pechochar</STRONG>
               returns  <STRONG>ERR</STRONG>  if  the  window  is  not  really  a  pad, and the
               associated call to <STRONG>wechochar</STRONG> returns <STRONG>ERR</STRONG>.

          <STRONG>pecho_wchar</STRONG>
               returns <STRONG>ERR</STRONG> if  the  window  is  not  really  a  pad,  and  the
               associated call to <STRONG>wecho_wchar</STRONG> returns <STRONG>ERR</STRONG>.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       <STRONG>pechochar</STRONG> may be implemented as a macro.

       <EM>curses</EM>  documentation  is  traditionally  averse to motivating the term
       "pad".  The Apollo Aegis  workstation  operating  system  (<EM>circa</EM>  1981)
       supported a graphical pad feature.

       <STRONG>o</STRONG>   These  graphical  pads  could  be  much  larger than the computer's
           display.

       <STRONG>o</STRONG>   The read-only output from a  command  could  be  scrolled  back  to
           inspect and select text from the pad.

       The two uses may be related.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       X/Open Curses Issue 4 describes these functions.  It specifies no error
       conditions for them.

       SVr4 describes a successful return value  only  as  "an  integer  value
       other than <EM>ERR</EM>".

       The  behavior  of  <EM>subpad</EM>  if  the  parent  window  is  not  a  pad  is
       undocumented, and is not checked by the vendor Unix implementations.

       <STRONG>o</STRONG>   SVr4 <EM>curses</EM>'s <EM>newpad</EM> sets a flag in the <EM>WINDOW</EM> structure indicating
           that the window is a pad.

           However,  it  uses this information only in <EM>waddch</EM> (to decide if it
           should call <EM>wrefresh</EM>) and <EM>wscrl</EM> (to avoid  scrolling  a  pad);  its
           <EM>wrefresh</EM>  does  not  check  it  to  ensure  that  a pad is properly
           updated.

       <STRONG>o</STRONG>   Solaris  <EM>xcurses</EM>  checks  whether  a  window  is  a  pad   in   its
           <EM>wnoutrefresh</EM>, returning <EM>ERR</EM> in that case.

           However,  it  sets the flag on subwindows only if the parent window
           is a pad.  Its <EM>newpad</EM> does not set this information.  Consequently,
           the check never fails.

           It   makes   no   comparable   check   in  <EM>pnoutrefresh</EM>  --  though
           interestingly enough, a comment in the source code states that  the
           lack of a check was an MKS extension.

       <STRONG>o</STRONG>   NetBSD 7  <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <EM>newpad</EM> and
           <EM>subpad</EM>, aiding  itself  to  distinguish  between  <EM>wnoutrefresh</EM>  and
           <EM>pnoutrefresh</EM>.

           It  does  not  check for the case where a subwindow is created in a
           pad using <EM>subwin</EM> or <EM>derwin</EM>.

           Its <EM>dupwin</EM>  returns  a  regular  window  when  duplicating  a  pad.
           Likewise,  its  <EM>getwin</EM>  always  returns a window, even if the saved
           data was from a pad.

       <EM>ncurses</EM>:

       <STRONG>o</STRONG>   sets a flag in the <EM>WINDOW</EM> structure for <EM>newpad</EM> and <EM>subpad</EM>,

       <STRONG>o</STRONG>   allows a <EM>subwin</EM> or <EM>derwin</EM> call to succeed having a  pad  parent  by
           forcing the subwindow to be a pad,

       <STRONG>o</STRONG>   checks  in  both  <EM>wnoutrefresh</EM> and <EM>pnoutrefresh</EM> to ensure that pads
           and windows are handled distinctly, and

       <STRONG>o</STRONG>   ensures  that  <EM>dupwin</EM>  and  <EM>getwin</EM>  treat   pads   versus   windows
           consistently.


</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
       SVr2  (1984) introduced <EM>newpad</EM>, <EM>prefresh</EM>, and <EM>pnoutrefresh</EM>, documenting
       them in a single line each.

       SVr3 (1987) added <EM>subpad</EM> and <EM>pechochar</EM>,  and  provided  more  extensive
       documentation.

       The  System V  Interface  Definition,  Version  4  (1995),  specified a
       function named <EM>pechowchar</EM>.  This was a later addition  to  SVr4.<EM>x</EM>,  not
       appearing  in  the  first  SVr4 (1989).  It differs from X/Open's later
       <EM>pecho</EM><STRONG>_</STRONG><EM>wchar</EM> in that its <EM>wstr</EM>  parameter  was  a  <EM>chtype</EM>  instead  of  a
       <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, and was not <EM>const</EM>-qualified.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>



ncurses 6.5                       2025-01-18                      <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-newpad">newpad</a></li>
<li><a href="#h3-subpad">subpad</a></li>
<li><a href="#h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></li>
<li><a href="#h3-pechochar">pechochar</a></li>
<li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
